home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Auge 4000 / Auge 4000 #45 (1990-06-20)(Amiga User Gruppe Einzugsgebiet 4000).zip / Auge 4000 #45 (1990-06-20)(Amiga User Gruppe Einzugsgebiet 4000).adf / ANWENDUNGEN / Ncomm / Script.doc < prev    next >
Text File  |  1990-06-08  |  18KB  |  592 lines
  1. The NComm V1.9 scriptlanguage
  2. =============================
  3.  
  4. A scriptfile is an ASCII textfile that consists of different commands,
  5. separated by  one or more  linefeeds.  Edit the  scriptfiles with your
  6. favourite  editor.  Only  one  command is  allowed per line, but blank
  7. lines are also OK. A line can consist of blanks before the command and
  8. between parameters.  Comments can be added by entering a semicolon.  A
  9. label is marked with a colon as its last character, e.g. "quit:".  The
  10. script  commands  are case independent,  but strings within quotes are
  11. not.
  12.  
  13. Scripts  are mainly used to automate logons, or to companion you while
  14. you  are  online.   Scripts  can also perform more advanced functions,
  15. like  grabbing  mail  and perhaps posting it on another board (or even
  16. printing it!).  You set the limits...
  17.  
  18. Two example  scripts and  one Host-Mode script have been included with
  19. the NComm package.  Take a look at them if you don't understand how to
  20. use the commands.
  21.  
  22. Important:   The  filenames  specified in a scriptfile are relative to
  23. the   current   directory,   NOT   the  default  upload  and  download
  24. directories!
  25.  
  26.  
  27. Summary of Script commands
  28. --------------------------
  29.  
  30.         ASCSEND
  31. Starts ASCII text send of the filename given. Example:
  32.  
  33. ASCSEND "df1:text/msg"
  34.  
  35. The  TIMEOUT command also concerns ASCSEND.  If ASCSEND is halted by a
  36. ^S  and  no  ^Q  has  been  received within the timelimit specified by
  37. TIMEOUT,  the  script  will  go on with the next command.  XON will be
  38. turned on before ASCSEND.
  39.  
  40. ----------------------------------------------------------------------
  41.  
  42.         BEEP
  43. Will  cause  an audible 'beep' of the terminal and / or will flash the
  44. screen  and / or will bring the screen to front, depending on what you
  45. have  configured  in  the  SCREEN  menu.   Nothing is sent through the
  46. serial port.
  47.  
  48. ----------------------------------------------------------------------
  49.  
  50.         BREAK
  51. Sends a break to the host machine. Equivalent to SEND "\l".
  52.  
  53. ----------------------------------------------------------------------
  54.  
  55.         CAPTURE
  56. Toggles ASCII capture on/off. Examples:
  57.  
  58. CAPTURE "filename"
  59. Will  open the capture file and turn on capture.  It will be opened in
  60. 'append mode' if the file exists...
  61.  
  62. CAPTURE SUS
  63. Will suspend capture.  Capture can be turned on again with the command
  64. CAPTURE ON
  65.  
  66. CAPTURE OFF
  67. Will  turn  capture off and close the file.  The file cannot be opened
  68. again with the CAPTURE ON command.
  69.  
  70. ----------------------------------------------------------------------
  71.  
  72.         CD
  73. Problems  occur  when  the "CD" command is used with the CLI function.
  74. The  "CD"  command  has  therefore  been  made a special function.  It
  75. simply  changes  the directory that is to be used for commands started
  76. with the "CLI" function.
  77.  
  78. Example:
  79.  
  80. CD "RAM:"       ;Will change the current working directory to 'RAM:'
  81.  
  82. ----------------------------------------------------------------------
  83.  
  84.         CHAIN
  85. Will start a new script.  The control will never return to the calling
  86. script.   This  is  useful  when  you need extremely long scripts that
  87. won't fit in memory.
  88.  
  89. Example:
  90.  
  91. CHAIN "NComm:ReadNews.script"
  92.  
  93. ----------------------------------------------------------------------
  94.  
  95.         CLI
  96. Will  execute  a program or a command.  The output from these programs
  97. and  commands  will  occur  in the NComm window.  This command will be
  98. relative to the directory you were standing in when you started NComm.
  99.  
  100. Please  note;  Current  Directory can not be set with the CLI command,
  101. probably  due  to  problems with the Amiga operating system.  The "CD"
  102. function must therefore be used for this purpose.
  103.  
  104. Examples:
  105.  
  106. CLI "dir dh0:comms"
  107. CLI "type ram:foo.bar"
  108. CLI "pkax ram:grabfile.arc"
  109.  
  110. ----------------------------------------------------------------------
  111.  
  112.         CLRSTACK
  113. This  command  clears  the  RETURN  stack,  i.e.   it  forgets  active
  114. subroutine  calls (gosubs).  The command is handy at error situations,
  115. when  you  wish to "jump out" of the program and start over again, for
  116. example in conjunction with TIMEOUT or WHEN commands.
  117.  
  118. ----------------------------------------------------------------------
  119.  
  120.         CONFIG
  121. Will read a new configuration file.  Example:
  122.  
  123. CONFIG "NComm:MBBS.config"
  124.  
  125. ----------------------------------------------------------------------
  126.  
  127.         CONVERSE
  128. Will wait for a prompt from the host machine and answer it.
  129.  
  130. Examples:
  131.  
  132. CONVERSE "Enter your name:" "Name\n"   ;Waits for 'Enter your name:'
  133. CONVERSE "enter your password:" "\p\n" ;Sends phonebook password + CR
  134. CONVERSE "Command:" "G\n"              ;Sends 'G' and newline
  135.  
  136. ----------------------------------------------------------------------
  137.  
  138.         DELAY
  139. The  script  program  will take a break.  The program will function as
  140. normal.
  141.  
  142. Examples:
  143.  
  144. DELAY 5                 ;Wait 5 seconds
  145. DELAY UNTIL 12:00       ;Wait until 12 o'clock.
  146.  
  147. ----------------------------------------------------------------------
  148.  
  149.         DIAL
  150. Will  dial  one  or  more  phonenumbers.  Can also dial entries in the
  151. phonebook.   If  you  choose  to  dial  phonenumbers,  use the command
  152. 'DIAL#'.   The  numbers must be placed within quotation marks.  If you
  153. choose to dial more than one number, the numbers can be separated by a
  154. comma.
  155.  
  156. Examples:
  157.  
  158. DIAL# "454143"
  159. DIAL# "380949", "493210", "454143"
  160.  
  161. Named  entries  in  the  phonebook  can  be  dialled by specifying the
  162. boardname within quotation marks.  You only have to specify the number
  163. of  letters  required  to  separate  the  board  from the others.  The
  164. name is not case sensitive.
  165.  
  166. Examples:
  167.  
  168. DIAL "AmigaBBS"
  169. DIAL "rode", "Mike's", "media"
  170. DIAL "Rodeløkka (M)BBS"
  171.  
  172. ----------------------------------------------------------------------
  173.  
  174.         DLWHEN
  175. Deletes  the last defined WHEN command.  Repeated usage will succesive
  176. delete the "previous" WHEN command.  See:  WHEN.
  177.  
  178. ----------------------------------------------------------------------
  179.  
  180.         DOWNLOAD
  181. Will download a file from the host machine.  The protocol specified in
  182. the  TRANSFER  menu will be used as long as nothing else is specified.
  183. If you want to specify another protocol, enter a comma and a letter.
  184. The filename is "dummy" when using Zmodem.
  185.  
  186. X == Xmodem, Y == Ymodem, B == Ymodem-B, G == Ymodem-G, Z == Zmodem.
  187.  
  188. Examples:
  189.  
  190. DOWNLOAD "df1:junk"             ;Will use the default protocol
  191. DOWNLOAD "df0:trash",X          ;Will always use Xmodem
  192.  
  193. ----------------------------------------------------------------------
  194.  
  195.         DTENTHS
  196. This  is  a much more precise delay command, but only use this command
  197. when  this  accuracy is needed, since it will lock up the system.  The
  198. DTENTHS parameter is the number of tenth seconds to wait.
  199.  
  200. Examples:
  201.  
  202. DTENTHS 2       ;Wait 0.2 seconds
  203. DTENTHS 16      ;Wait 1.6 seconds
  204.  
  205. ----------------------------------------------------------------------
  206.  
  207.         DUMP
  208. Command  for debugging a script.  It dumps a list of all variables and
  209. what they contain, on screen.
  210.  
  211. ----------------------------------------------------------------------
  212.  
  213.         DWHENS
  214. Will disable all previously used WHEN commands. See: WHEN.
  215.  
  216. ----------------------------------------------------------------------
  217.  
  218.         ECHO
  219. This  command defines if characters read by the INPUT command shall be
  220. echoed.   ECHO ON should be used when input is read from a user in the
  221. other  end. ECHO OFF should be used when input is read from a Bulletin
  222. Board  System, or when the user is not supposed to see what he writes.
  223.  
  224. ECHO  should  be  turned  ON  if the functions ASCSEND and MSGSEND are
  225. supposed  to  echo text locally.  The output from the CLI command will
  226. be sent to the serial port if ECHO has been turned on.
  227.  
  228. ----------------------------------------------------------------------
  229.  
  230.         END
  231. Will  stop  the  execution  of the script.  This command is especially
  232. useful in front of subroutines.
  233.  
  234. Example:
  235.  
  236. WHEN "Read>" GOSUB next
  237. WAIT "No more unread."
  238. END
  239.  
  240. Next: SEND "\n"
  241.       MESSAGE "(Skipping to next unread)\n"
  242.       RETURN
  243.  
  244. ----------------------------------------------------------------------
  245.  
  246.         GOSUB
  247. Will  call  a  named subroutine.  Useful when you want to use the same
  248. command  many  times  within  a  script, or in connection with WHEN or
  249. TIMEOUT.   The  subroutine  is ended with 'RETURN', and the control is
  250. passed to the line following the GOSUB afterwards.
  251.  
  252. Example:
  253.  
  254. GOSUB myRoutine
  255. END
  256.  
  257. MyRoutine: MESSAGE "Fooo\n"
  258.            BEEP
  259.            RETURN
  260.  
  261. ----------------------------------------------------------------------
  262.  
  263.         GOTO
  264. Ever heard of this? Will jump to a named place in the script.
  265.  
  266. Example:
  267.  
  268. GOTO quit
  269. ...
  270. quit: CAPTURE OFF
  271.       HANGUP
  272.       END
  273.  
  274. ----------------------------------------------------------------------
  275.  
  276.         HANGUP
  277. Will send the hangup string to the modem.
  278.  
  279. ----------------------------------------------------------------------
  280.  
  281.         IF <expression> THEN <operation>
  282.  
  283. It  should be obvious what this command does.  A valid expression can
  284. be either a comparison of two strings or a check for a file.  The
  285. exclamation mark ('!') works as a boolean 'NOT' operator.
  286.  
  287. String comparisons are performed with the "==" operator, which tests for
  288. case independent equality, i.e.  "foo" == "FOO" is TRUE; 
  289. !"bar" == "yum" is TRUE (because of the '!' (NOT) operator)
  290.  
  291. EXISTS  checks  if a file exists.  The following are examples on valid
  292. IF commands:
  293.  
  294.         IF $password == "abcdef" THEN MESSAGE "Access granted\n"
  295.         IF !$password == "xyz" THEN GOTO KillUser
  296.         IF EXISTS "NComm:host.config" THEN CONFIG "NComm:host.config"
  297.         IF !EXISTS $file THEN SEND "File not found!\n"
  298.  
  299. The whole command must be placed on a single line, including the 'THEN'
  300. part...
  301.  
  302. ----------------------------------------------------------------------
  303.  
  304.         INPUT
  305. This  command  reads  input  from  the  serial port and places it in a
  306. variable  until  a  specific string has been received.  ^H (backspace)
  307. deletes  the  last  character,  ^U  deletes  the  whole  string.   The
  308. searchstring  will  not  be added to the variable.  Control characters
  309. will not be added.  Example:
  310.  
  311.         SEND "Enter your first name: "
  312.         INPUT $name "\r" ;Input will be placed in the variable 'name'
  313.                          ;until carriage return is received.
  314.  
  315. The  TIMEOUT  command  also  concerns  the INPUT command.  The timeout
  316. defines  how long INPUT shall wait for the terminating string ("\r" in
  317. the mentioned example).  Example:
  318.  
  319.         TIMEOUT 180 Goto BiBi
  320.         SEND "Enter a command: "
  321.         INPUT $cmd "\r"
  322.         ...
  323.  
  324. BiBi:   SEND "\n\nLooks like you fell asleep!!  Bye-bye!\n"
  325.         HANGUP
  326.         END
  327.  
  328. It is also possible to read a single character without having to
  329. wait for ENTER or other strings:
  330.  
  331.         INPUT $char ""
  332.  
  333. INPUT  can  both  be  used for reading input from a user in connection
  334. with  "Host  Mode",  or  grabbing pieces of text from a Bulletin Board
  335. System;
  336.  
  337.         WAIT "Bulletins have been updated: "
  338.         INPUT $bull " "
  339.  
  340. ----------------------------------------------------------------------
  341.  
  342.         LOADKEYS
  343. Will read a new macrokeys file.
  344.  
  345. Example:
  346.  
  347. LOADKEYS "NComm:dec.Keys"
  348.  
  349. ----------------------------------------------------------------------
  350.  
  351.         LOADPHONE
  352. Will read a new phonebook file.
  353.  
  354. Example:
  355.  
  356. LOADPHONE "NComm:dialdir.phone"
  357.  
  358. ----------------------------------------------------------------------
  359.  
  360.         MESSAGE
  361. Will  write  a  message  on  the  screen.  Nothing is sent through the
  362. serial port.
  363.  
  364. Example:
  365.  
  366. MESSAGE "\fReading mail...\n"
  367. MESSAGE "Storing mail in file \"DF1:Mail.txt\"\n"
  368.  
  369. ----------------------------------------------------------------------
  370.  
  371.         MSGSEND
  372. Same  as the "message send" function in the TRANSFER menu, will upload
  373. a message.
  374.  
  375. Example:
  376.  
  377. MSGSEND "DF1:tekst/msg"
  378.  
  379. ----------------------------------------------------------------------
  380.  
  381.         PRINTER
  382. Turns the printer ON or OFF.
  383.  
  384. Example:
  385.  
  386. PRINTER ON      ;Will turn on the printer
  387. PRINTER OFF     ;Will turn off the printer
  388.  
  389. ----------------------------------------------------------------------
  390.  
  391.         QUIT
  392. Exits NComm.
  393.  
  394. ----------------------------------------------------------------------
  395.         REPEAT<->UNTIL <expression> ...
  396. This  command  performs what is situated between REPEAT and UNTIL.  If
  397. the  expression  is  FALSE/TRUE,  the procedure will be repeated.  See
  398. "IF...THEN" for a discussion of valid expressions. The command has the
  399. same restrictions as WHILE/ENDWHILE.
  400.  
  401. Example:
  402.  
  403. REPEAT
  404.         SEND "Enter command: "
  405.         INPUT $cmd "\r"
  406.         GOSUB DoCommand
  407. UNTIL $cmd == "quit"
  408.  
  409.  
  410. ----------------------------------------------------------------------
  411.  
  412.         REQUEST
  413. This  function  is  used  when  the  scriptfile  is  run without human
  414. presence.   It  will  then  be  unpreferable  that  AmigaDOS puts up a
  415. requester  if  problems  occur (disk full, read / write error etc.) By
  416. turning request OFF, this is disabled.
  417.  
  418. Example:
  419.  
  420. REQUEST OFF     ;Turns requesters off
  421. REQUEST ON      ;Will turn the requesters back on again
  422.  
  423. ----------------------------------------------------------------------
  424.  
  425.         RETURN
  426. Returns from a subroutine. See GOSUB.
  427.  
  428. ----------------------------------------------------------------------
  429.  
  430.         SEND
  431. Sends a string to the host machine.
  432.  
  433. Examples:
  434.  
  435. SEND "\n"       ;Linefeed
  436. SEND "Read\n"   ;'Read' plus a CR
  437. SEND "\m1^z"    ;Macro #1 plus a 'Control-Z'
  438. SEND "\p\n"     ;The password stored in the phonebook plus a CR
  439.  
  440. ----------------------------------------------------------------------
  441.  
  442.         SET
  443. This  command  is  used  for assigning values to variables.  Variables
  444. have  name  in  the form $name where 'name' starts with a letter.  The
  445. value  must be of type string, either a literal (with quotation marks)
  446. or another variable.
  447.  
  448. Examples:
  449.  
  450.         SET $name = "Daniel"
  451.         SEND $name
  452.  
  453.         SET $filename = "RAM:foo"
  454.         CAPTURE $filename
  455.  
  456.         SET $UserName = $name
  457.  
  458. Variables  can  be  used  everywhere  where  strings  are expected.  A
  459. pre-defined  variable  $date  contains the current date and time.  The
  460. variable  $ncomm  contains  the  current  version  number.  The variable
  461. $baud contains the current baud rate. It is also possible to concatenate
  462. several variables and/or literals;
  463.  
  464.         SEND $name"\n"
  465.         SET $directory = "NComm:files/"
  466.         INPUT $filename "\r"
  467.         UPLOAD $directory$filename
  468.  
  469. It is not valid referring to variables having no value assigned.
  470.  
  471. ----------------------------------------------------------------------
  472.  
  473.         TIMEOUT
  474. This  command lets you configure how long NComm should wait in a WAIT,
  475. CONVERSE  or INPUT command.  Default timeout is 'forever', but this is
  476. not  preferable if the script is running without human assistance.  If
  477. the  host machine does not answer, it is reasonable to believe that it
  478. has  hung,  and a scriptfile should then automatically disconnect from
  479. the system.  The TIMEOUT command can be used in many ways.
  480.  
  481. Examples:
  482.  
  483. TIMEOUT 10
  484. Means  that  NComm shall wait a maximum of 10 seconds.  If no text has
  485. been  received  within  the  timelimit, NComm will go on with the next
  486. command.
  487.  
  488. TIMEOUT 10 SEND "\n"
  489. Specifies  that NComm is to wait a maximum of 10 seconds for each WAIT
  490. or  CONVERSE  command.   If  the  specified text has not been received
  491. within  10 seconds, NComm will send a linefeed to the host machine and
  492. will  continue  waiting  for  the  text.   NComm will continue sending
  493. linefeeds every 10th second until the host machine has answered.
  494.  
  495. TIMEOUT 0
  496. NComm is to go back to the default mode, i.e. wait forever.
  497.  
  498. Example of typical usage:
  499.  
  500. TIMEOUT 30 GOTO quit
  501. CONVERSE "Enter your name:" "Daniel Bloch\n"
  502. CONVERSE "Enter your password:" "gruff\n"
  503. CONVERSE "Command:" "GRAB\n"
  504. ...
  505. ...
  506. END
  507.  
  508. quit: MESSAGE "\n\nThe board has hung, call the SysOp!!!\n"
  509.       BEEP
  510.       HANGUP ;Hang up so that we won't get a shock when
  511.       END    ;the next phonebill arrives!
  512.  
  513. ----------------------------------------------------------------------
  514.  
  515.         UPLOAD
  516. Uploads  a  file to the host machine.  See the 'DOWNLOAD' function for
  517. the correct syntax.
  518.  
  519. ----------------------------------------------------------------------
  520.  
  521.         WAIT
  522. Waits  for  a  special  text to be received.  Will wait forever if the
  523. TIMEOUT command has not been used.
  524.  
  525. Examples:
  526.  
  527. WAIT ""         ;Wait for 'anything'
  528. WAIT "\n"       ;Wait for a linefeed
  529. WAIT "Command:" ;Wait for 'Command:'
  530.  
  531. ----------------------------------------------------------------------
  532.  
  533.         WHILE <expression> DO ... ENDWHILE
  534. This  function  performs what is situated within DO and ENDWHILE until
  535. the expression is TRUE/FALSE.
  536.  
  537. Example:
  538.  
  539. SET $cmd = ""
  540. WHILE !$cmd == "quit" DO
  541.         SEND "Enter command: "
  542.         INPUT $cmd "\r"
  543.         GOSUB DoCommand
  544. ENDWHILE
  545.  
  546. It  is  not  valid  jumping out of a WHILE/ENDWHILE loop using GOTO or
  547. RETURN.   It  is  still  possible  to exit the loop using GOTO and the
  548. command   CLRSTACK. 
  549.  
  550. ----------------------------------------------------------------------
  551.  
  552.         WHEN
  553. Defines what to do when a special text is received.
  554.  
  555. Typical example:
  556.  
  557. WHEN "--more--" SEND " "
  558.  
  559. This  command  will  make  NComm  send  a  'blank'  line every time it
  560. receives the 'more' prompt from the host machine.  This is independent
  561. of  where  in the script  you reside.  It is possible to specify up to
  562. ten such textstrings.
  563.  
  564. Example:
  565.  
  566. WHEN "--more--" SEND " "
  567. WHEN "NO CARRIER" END
  568. WHEN "Sysop is coming online!" GOSUB ShutUp
  569. WHEN "No more unread" GOTO Quit
  570.  
  571. Loop: CONVERSE "Command:" "\n"
  572.       GOTO loop
  573.  
  574. Quit: SEND "G;Y\n"
  575.       END
  576.  
  577. ShutUp: SEND "I'm not at home! You are chatting with a scriptfile!\n"
  578.         SEND "Send BIBI at the speed of light!!!\n\n"
  579.         RETURN
  580.  
  581. ----------------------------------------------------------------------
  582.  
  583.         WRITE
  584. This command writes a textstring to a file. If the file exists, the
  585. string will be appended to the file. Example:
  586.  
  587.         WRITE "NComm:host/log" "Logged in: "$username"\n"
  588.               |                |
  589.               Name of file     String
  590.  
  591. ----------------------------------------------------------------------
  592.